<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta name="copyright" content=
    "Copyright (c) IBM Corporation and others 2010, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta http-equiv="Content-Style-Type" content="text/css" />
    <title>
      Formatter
    </title>
    <link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type=
    "text/css" />
  </head>

  <body>
    <h1>
      Formatter
    </h1>
    <p>
      In the Java editor press <b>Ctrl+Shift+F</b> on code to format it. If no
      selection is set then the entire source is formatted otherwise only the
      selection will be. Some tips for using the formatter are listed in the
      paragraphs of this chapter.
    </p>
    <p>

      Note that the Java Formatter preferences are accessible on the <a class=
      "command-link" href=
      'javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.jdt.ui.preferences.CodeFormatterPreferencePage)")'>
      <img src="PLUGINS_ROOT/org.eclipse.help/command_link.svg" alt=
      "Opens the Java Formatter preference page" /> <b>Java Formatter</b></a>
      preference page.
    </p>
    <h2>
      Disabling formatter inside sections
    </h2>
    <p>

      You can disable/enable the formatter in one or several sections in the
      code as shown in the sample below:
    </p><img src="images/formatter-disabling-enabling-tags.png" alt=
    "Java formatter example. Some code using disabling and enabling tags." />
    <p>
      The snippet above use default tag names, but they can be changed on the
      <b>Off/On tags</b> tab of the Java Formatter preference page.
    </p>
    <h2>
      Wrap outermost method calls
    </h2>
    <p>

      Since version 3.6, the Java formatter now tries to wrap the outermost
      method calls first to have a better output when wrapping nested method
      calls.
    </p>
    <p>
      Here is an example of a formatted code where the formatter has wrapped
      the line between the arguments of the outermost message call to keep each
      nested method call on a single line:
    </p><img src="images/formatter-prefer-wrapping-outer-expressions.png" alt=
    "Java formatter example. The simple snippet with the formatted nested method calls." />
    <p>
      A new preference allows you to disable this strategy, typically if you
      want to format your code as before, then uncheck the <b>Prefer wrapping
      outer expressions</b> preference accessible on the <b>Line wrapping</b>

      tab of the Java Formatter preference page.
    </p>
    <p>
      <b>Note:</b> Currently the new strategy only applies to nested method
      calls, but that might be extended to other nested expressions in future
      versions.
    </p>
    <h2>
      Condense Javadoc and block comments
    </h2>
    <p>

      Users can reduce the number of lines of formatted multi-lines comments as
      shown in the example below:
    </p><img src="images/formatter-condense-multi-lines-comments.png" alt=
    "Java formatter example. The simple snippet with the block and Javadoc comments formatted with less lines than with the default profile." />
    <p>
      To activate this behavior uncheck the <b>/* and */ on separate lines</b>
      preference accessible on the <b>Comments</b> tab of the Java Formatter
      preference page.
    </p>
    <p>

      The same kind of preference is also available for the Javadoc comments.
    </p>
    <h2>
      Preserve user line breaks
    </h2>
    <p>
      Users can preserve line breaks by not joining lines in code or comments.
    </p>
    <p>
      For example, the already wrapped lines of the <code>return</code>

      statement in the following test case:
    </p><img src="images/formatter-join-lines-before.png" alt=
    "Example of Code to Format" />
    <p>
      will be preserved by the formatter when the <b>Never join lines</b>
      preference is used, hence produces the following output when formatted:
    </p><img src="images/formatter-join-lines-after.png" alt=
    "Coded Formatted with Never Join Lines" />
    <p>
      To activate this behavior check the <b>Never join lines</b> preference
      accessible on the <b>Line Wrapping</b> and the <b>Comments</b> tabs of
      the Java Formatter preference page.</p>

    <h3 class="related">Related concepts</h3>
      <a href="../concepts/concept-java-editor.htm">Java editor</a><br />
      <a href="../concepts/concept-jdt.htm">Java development tools (JDT)</a>

    <h3 class="related">Related references</h3>
      <a href="../reference/ref-menu-edit.htm">Edit menu</a><br />
      <a href="../reference/preferences/java/ref-preferences-editor.htm">Java
      editor preferences</a><br />
      <a href=
      "../reference/preferences/java/codestyle/ref-preferences-formatter.htm">Formatter
      preferences</a>
  </body>
</html>
